/***************************************************************************
 *   Copyright (C) 2006 by Yuri Ovcharenko                                 *
 *   amwsoft@gmail.com                                                     *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************/
#ifndef DCPLUGIN_H
#define DCPLUGIN_H

#include <QtGui>

/**
 * @class DCPlugin
 * @brief Provides interface for plugins.
 *
 * Functionality of DC can be extended via plugins system.
 * Plugins interface includes basic plugin class @a DCPlugin.
 * DCPlugin provides standard QT-4 plugins interface. This is abstract class.
 *
 * To write plugin simply subclass DCPlugin and write its own methods.
 */

class DCPlugin
{
	public:

	/**
	 * @enum PortConnection
	 * @brief Describes plugin access method to the serial port.
	 */
		enum PortConnection {
			PortConcurent, /**< The plugin uses port by its own procedures. The main program
					* needs to release port to make port available for plugin.
					* Plugin has @a atStart (bool needClose) and @a stopped (bool canOpen) signals and emit this
					* signal befor opening and after closing port respectively.
				        */
			PortDirect,    /**< The plugin uses main program interface for communicate over serial port.
					* @warning PortDirect connection type is not implemented at this time!
				        */
			PortNone,      /**< The plugin is not uses serial port. */
		};

	/**
	 * @portConnection
	 * @brief Returns connection type.
	 *
	 * Return the serial port connection type. Plugin need to implement this function to
	 * inform main program of wich connection it used.
	 *
	 * @sa PortConnection
	 */
		virtual PortConnection portConnection() = 0;

	/**
	 * @~DCPlugin()
	 * @brief Destructs DCPlugin object.
	 *
	 * @note There is no explicitly defined constructor.
	 */
		virtual ~DCPlugin() {};

	/**
	 * @DCPlugin::name()
	 * @brief Return plugin's name.
	 *
	 * The name of plugin used by @a PluginManager.
	 * PluginManager uses name to find plugin over shared libraries. This name
	 * saved in configuration files to manage plugins at next program startup.
	 * @warning It is strongly recommended to avoid using QT internationalisation interface
	 * for plugin's name.
	 * @sa PluginManager
	*/
		virtual QString name() const = 0;

	/**
	 * @widget
	 * @brief Return plugin's widget.
	 *
	 * If the plugin has widget this functions return pointer to this widget.
	 * If plugin has no widget this function returns zero.
	 * Plugin's widget used to provide user interface for plugin.
	 * This plugin's widget can implement SIGNAL/SLOT interface to interact with main program.
	 *
	 * @sa deleteWidget
	 */
		virtual QWidget *widget() = 0;

	/**
	 * @deleteWidget
	 * @brief Delete plugin's widget.
	 *
	 * This function can be used to delete plugin's widget on deactivation of plugin.
	 * @sa widget
	 */
		virtual void deleteWidget() = 0;

	/**
	 * @saveSettings
	 * @brief Saves the settings of plugin.
	 *
	 * This function is called by @a PluginManager to save settings.
	 * Settings saved on plugin deactivation or closing program.
	 * @param dir	Directory to save plugin's settings file to.
	 * @sa restoreSettings PluginManager
	 */
		virtual void saveSettings(const QString & dir) = 0;

	/**
	 * @restoreSettings
	 * @brief Restores the settings of plugin.
	 *
	 * This function is called by @a PluginManager to restore settings.
	 * Settings restored on plugin activation.
	 * @param dir	Directory where plugin's settings file is.
	 * @sa saveSettings PluginManager
	 */
		virtual void restoreSettings(const QString & dir) = 0;
};

Q_DECLARE_INTERFACE(DCPlugin, "DCPlugin");

#endif
